home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / qwik41.arc / QWIK41.DOC < prev    next >
Text File  |  1989-06-12  |  23KB  |  495 lines
  1.                                                         May 02, 1988
  2.  
  3.                               QWIK SCREEN UTILITIES
  4.                                    Version 4.1A
  5.  
  6.         PURPOSE:
  7.  
  8.         QWIK screen utilities permit fast screen writing on IBM 
  9.         compatibles on any IBM or Hercules adapter including the new PS/2 
  10.         systems without "snow" or flicker effects and is compatible with 
  11.         ANY column format (e.g. 40/80 or variable).  Written in MASM and 
  12.         implemented in a unit for Turbo Pascal 4.0, these procedures are 
  13.         lightning fast.  The code has also been condensed as much as 
  14. |       possible without sacrificing speed - only 1.7k bytes of compiled 
  15. |       code for all 23 procedures!  QWIK utilities allow you to write to 
  16.         the screen in absolute coordinates on any video page and are not 
  17.         confined to a Turbo window or to just page 0.
  18.  
  19.  
  20.         TEST DRIVE:
  21.  
  22. |       First copy QWIK41A.TPU to QWIK.TPU.  Compile and run QWIKDEMO.PAS 
  23.         to get a feel for features and speed.
  24.  
  25.  
  26.         IMPROVEMENTS:
  27.  
  28. |       Four new procedures have been added - QwriteMore, QwriteMoreA, 
  29. |       QfillMore, QattrMore.  QWIK now keeps track of where the last 
  30. |       character or attribute was written on the screen.  Similar to TP's 
  31. |       Write procedure, these Q*More procedures do not need Row and Col 
  32. |       parameters, but simply continue writing where any Q* procedure 
  33. |       left off.  This is essential for mid-stream attribute changes.  In 
  34. |       addition, Qinit was improved for detection of dual monitors and 
  35. |       Hercules cards.  Background color constants have been added for 
  36. |       convenience and speed.  The the critical timing for the IBM PC 
  37. |       (8088) with CGA has now been solved.
  38.  
  39.  
  40.         FILES:
  41.  
  42.         In this version, QWIK41A.ARC contains:
  43.  
  44.           Qwik41a .tpu:  Compiled QWIK41 unit of 1300 lines of assembler.
  45.           Qwik41  .pas:  Source code for QWIK41A.TPU.  (MASM source code 
  46.                          and object files are not included.)
  47.           Qwik41  .doc:  This document.
  48.           QwikDemo.pas:  A demonstration program showing the features and
  49.                          speed of all procedures and is written primarily
  50.                          for color cards, but also works on mono cards.
  51.           Qinit   .doc:  Document for Qinit procedure.
  52.           Qinitest.pas:  A program that verifies the equipment detected
  53.                          by the Qinit procedure.
  54.           Qbench  .pas:  A timing program that shows "screens/second" for
  55.                          the Q* procedures.
  56.           Cursor  .doc:  Document for cursor procedures and functions.
  57.           TimerD12.inc:  Include file to measure elapsed time.
  58.           License .arc:  ARC file containing license agreements
  59.  
  60.  
  61.         PROCEDURES AND FUNCTIONS:
  62.  
  63.         In this version, QWIK41A.TPU has the following procedures and 
  64.         functions.  To see the parameters needed, see QWIK41.PAS.
  65.  
  66.           One initializing procedure:
  67.             Qinit        - Initializing procedure executed by QWIK41A.TPU 
  68.                            which sets the global variables for the Q* 
  69.                            procedures.  It should be executed again after 
  70.                            a change from one text mode to another.
  71.           Three quick direct screen writing procedures, all work with or 
  72.           without attribute change:
  73.             Qwrite       - for any type string or char.
  74.             QwriteC      - for any type string or char; self-centering.
  75.             QwriteA      - for any type variable; specified length and 
  76.                            index.  (Array-like)
  77.           Four quick direct screen filling procedures in Rows-by-Cols 
  78.           block parameters:
  79.             Qfill        - repetitive filling with the same character;
  80.                            self-centering, with or without attribute 
  81.                            change.
  82.             QfillC       - Same as Qfill, but self-centering.
  83.             Qattr        - repetitive filling with the same attribute 
  84.                            only.
  85.             QattrC       - Same as Qattr, but self-centering.
  86.           Two quick screen storing procedures:
  87.             QstoreToMem  - Saves a Rows-by-Cols block to memory.
  88.             QstoreToScr  - Restores a Rows-by-Cols block to any screen 
  89.                            page.
  90.           Two quick video page changing procedures:
  91.             QviewPage    - Changes the page to be displayed - up to 8!
  92.             QwritePage   - Sets the page on which the Q* procedures are 
  93.                            writing.  You don't have to write just on the 
  94.                            displayed page!
  95.           Six quick cursor procedures and functions:
  96.             GotoRC       - inverse of Turbo's GotoXY but in absolute 
  97.                            coordinates rather than relative to a window.  
  98.                            It also works on any video page.
  99.             ChangeCursor - changes shape and visibility of the cursor; 
  100.                            saves old shape, too!
  101.             CursorOff    - Hides cursor.
  102.             CursorOn     - Reveals cursor, again.
  103.             WhereR       - Returns absolute row coordinate for the viewed 
  104.                            video page.
  105.             WhereC       - Returns absolute column coordinate for the 
  106.                            viewed video page.
  107.           Four quick appending procedures (like TP "Write") that start 
  108.           writing at QnextOfs in lieu of Row/Col parameters:
  109.             QwriteMore   - like Qwrite.
  110.             QwriteMoreA  - like QwriteA.
  111.             QfillMore    - like Qfill.
  112.             QattrMore    - like Qattr.
  113.  
  114.  
  115.         PROGRAMMING:
  116.  
  117. |       It is recommended that you copy QWIK41A.TPU to QWIK.TPU and just 
  118. |       do the following line in your programs:
  119.  
  120.            USES Qwik;
  121.  
  122.         TP 4.0 Startup - Borland improved the startup of any EXE file.  It 
  123.         checks for the video mode to see if it is a valid text mode 
  124.         (0..3,7).  If so, it remains in that mode.  If not, it is in a 
  125.         graphics mode and it is forced back into the computer's default 
  126.         text mode, whatever that may be.
  127.  
  128.         QWIK41 Startup - QWIK41A.TPU automatically runs Qinit the first 
  129.         time.  (Turbo's smart compiler does it just once no matter how 
  130.         many times it appears in USES statments throughout your program.)  
  131.         If you change from one text mode to another in a running program, 
  132. |       you still need to run Qinit again.  Be sure to read QINIT.DOC for 
  133. |       all of the available video card and system status values.
  134.  
  135.  
  136.         PARAMETERS:
  137.  
  138.         Row/Col - The procedures do not check for bounds on the screen,
  139.         so be sure to stay in range.  The procedures were designed for
  140.         the upper left column on the screen to be 1,1.  They also wrap to 
  141.         the next line; they do not truncate at EOL.  You of course can 
  142.         have something like Row:=1 and Col:=255 which is equivalent to 
  143.         Row:=3 and Col:=15 on a screen with 80 columns.
  144.  
  145.         ColL/ColR - In QwriteC, QfillC, and QattrC, the left and right 
  146.         columns are simply averaged.  To center on the full width of an 80 
  147.         column display, set ColL:=1 and ColR:=80.  To center on a certain 
  148.         column number, set both values equal to that column number.  Or, 
  149.         to center on any display, set ColL:=1 and ColR:=CRTcols.
  150.  
  151.         Rows/Cols - They can be any byte to define the block: Rows-by-
  152.         Columns starting at Row, Col.  Please keep Cols limited to one 
  153.         row.
  154.  
  155. |       Attr - Use the convenient attribute constants for the foreground 
  156. |       and background colors supplied in the QWIKxx.PAS file rather than 
  157. |       having to use TP functions or procedures to get a desired color, 
  158. |       for example:
  159. |
  160. |           Qwrite ( 1, 1,White+BlueBG,'My String');
  161. |
  162. |       will write the text with white on blue attributes.  Use of the 
  163. |       constant SameAttr, or negative values, suppress any changes to the 
  164. |       screen attributes and use what's currently on the screen.  Of 
  165. |       course, you can still use Turbo's TextColor and TextBackground 
  166. |       procedures, and then use TextAttr as a parameter.  Be aware that 
  167.         the 3270 PC ignores the foreground intensity bit, so there are 
  168.         only 8 colors.  In addition, 4 colors have different tints:
  169.  
  170.            PC Color     3270 PC Color
  171.            ------------ -------------
  172.            Cyan         Turquoise
  173.            Magenta      Pink
  174.            Brown        Yellow
  175.            Light Gray   White
  176.  
  177. |       ArrayLength - In QwriteA and QwriteMoreA, you can write arrays or 
  178.         partial strings by specifying the ArrayLength and the starting 
  179.         index (aStr[i]).  (Qwrite and QwriteC assume the length is the 
  180.         value at aStr[0] and the starting index is aStr[1].)  ArrayLength 
  181.         can be any word.  For example:
  182.  
  183.            MyString:='Step B: Testing out this line.';
  184.            QwriteA (1,1,-1,22,MyString[9]);
  185.  
  186.         will print out "Testing out this line."  Of course, MyString 
  187.         doesn't have to be a string - it can be any type variable or 
  188.         address in memory.
  189.  
  190.         aStr - One of the nice improvements of TP 4.0 is that the address 
  191.         of a string is always passed onto to the stack no matter if it's a 
  192.         string value or a variable.  So, there is no need to copy strings 
  193.         to the stack and thereby increasing speed.  The Qwrite* procedures 
  194.         only use the address.  "aStr" is of type "string", now, and not 
  195.         Str80 and there is no need to be concerned about incompatible 
  196.         string types
  197.  
  198.         Source/Dest - For Qstores*, this can be a pointer for the heap or 
  199.         an array variable.  Be sure there is sufficient room.  Storage 
  200.         requirements are: (Rows * Cols shl 1) which is two bytes for every 
  201.         column.  For pointers use a format such as:
  202.  
  203.             Var  MemPtr: ^byte;
  204.             GetMem (MemPtr,Rows*Cols shl 1);
  205.             QstoreToMem (Row,Col,Rows,Cols,MemPtr^);
  206.  
  207.         Page - The page range depends upon your adapter which is detected 
  208. |       with MaxPage.  See QINIT.DOC for the possible ranges.
  209.  
  210.  
  211. |       Q*MORE PROCEDURES
  212.  
  213. |       Purpose - Just as the TP Write and WriteLn procedures continue 
  214. |       where the last Write left off, the Q*More procedures, QwriteMore, 
  215. |       QwriteMoreA, QfillMore, and QattrMore, work similarly.
  216. |
  217. |       QnextOfs - Any time a Q* procedure (except QstoreToScr and 
  218. |       QstoreToMem) is used, the global variable QnextOfs is updated.  
  219. |       This value tells the Q*More procedure where to continue writing, 
  220. |       so you don't need Row or Col parameters.  This is especially 
  221. |       useful for midstream attribute changes:
  222. |
  223. |          Qwrite     ( 1, 1,White+BlueBG ,'There are');
  224. |          QwriteMore (      Yellow+BlueBG,' 5 ');
  225. |          QwriteMore (      White+BlueBG ,'minutes left.');
  226. |
  227. |       which will write "There are 5 minutes left." as white on blue 
  228. |       except "5" will be yellow on blue.  QnextOfs is universal so that 
  229. |       any Q*More procedure can follow any Q* procedure!  You can even 
  230. |       modify QnextOfs directly.  Just remember that it is 0-based and 
  231. |       that there are two bytes per displayed character.
  232.  
  233.  
  234.         PAGING:
  235.  
  236.         If you have a CGA or better, you already have memory on your card 
  237.         for more than the 80x25 display you normally see.  The two page 
  238.         procedures allow you to use QWIK utilities on these other pages 
  239.         and display which ever you choose.  However, Turbo's procedures 
  240.         such as Write, Window, and GotoXY are dedicated to page 0 only.
  241.         Be sure to end your programs with "QviewPage (0);". 
  242.  
  243.  
  244.         UPGRADING:
  245.  
  246.         Here's a list of steps to help you upgrade to QWIK41 from versions 
  247.         prior to QWIK40 on your programs:
  248.  
  249. |         1. Add "Uses Qwik;"
  250.           2. Delete the first Qinit.
  251.           3. Do a search and replace for the following names.
  252.                Search     Replace with
  253.                ---------  ---------------------
  254.                CardWait   CardSnow
  255.                Qwait      Qsnow
  256.                QwriteLV   QwriteA
  257.                QwriteCV   QwriteC
  258.                QwriteV    Qwrite
  259.                ActiveDD   ActiveDispDev
  260.                AltDD      AltDispDev
  261.                PCCAltDD   AltDispDevPCC
  262.                Vmode      VideoMode
  263.           4. Add "CheckSnow:=Qsnow" early in the program and after each 
  264.              Qinit if you use the CRT unit.
  265.           5. See REVISIONS for changes of type.
  266.  
  267.  
  268.         TIPS:
  269.  
  270.         CheckSnow - If you plan on using the standard CRT unit, place the 
  271.         following line early in your programs and after each Qinit.
  272.  
  273.            CheckSnow:=Qsnow;
  274.  
  275.         Qinit appears to be more extensive in it's testing for wait-for-
  276. |       retrace.  Then, Write and WriteLn will work faster if DirectVideo 
  277.         is true.  
  278.  
  279.         Multi-Tasking - Currently, QWIK does not attempt to modify 
  280.         Page0seg for multi-tasking software, but the variables have been 
  281.         set up so you can do this.  Take DESQview for example; rather than 
  282.         writing direct to screen memory, DESQview allocates a presentation 
  283.         buffer in RAM.  All direct screen write procedures can treat the 
  284.         presentation buffer just like the video buffer, except that Qsnow 
  285.         can always be false.  Then, DESQview copies the correct portions 
  286.         to the video buffer.  Here's an example procedure that would 
  287.         modify Page0seg:
  288.  
  289.           uses DOS;
  290.           procedure GetVideoBuffer (VAR Page0seg: word);
  291.           begin
  292.             Regs.es:=Page0seg;
  293.             Regs.di:=0;
  294.             Regs.ah:=$FE;
  295.             Intr ($10,Regs);
  296.             Page0seg:=Regs.es;
  297.           end;
  298.  
  299.         This procedure also works for 3270 PC.  If neither DESQview nor 
  300.         the 3270 PC are present, then Page0seg will still have the same 
  301.         value.
  302.  
  303.         To update the display on the 3270 PC when using multi-tasking, use 
  304.         the following procedure:
  305.  
  306.           uses DOS;
  307.           procedure UpdateVideoDisplay (Row, Col: byte; NumOfChars: word);
  308.           begin
  309.             Regs.es:=Page0seg;
  310.             Regs.di:=pred(Row)*CRTcols + pred(Col);
  311.             Regs.cx:=NumOfChars;
  312.             Intr ($10,Regs);
  313.             Qseg:=Page0seg;
  314.           end;
  315.  
  316.         where Row and Col is the position in the presentation buffer to be 
  317.         updated and only for NumOfChars.  CardSeg will still have the 
  318.         original segment of the video card.
  319.  
  320.         EgaMono - You should be aware that another constant also named 
  321.         EGAMono is used by the DetectGraph procedure in the Graph unit, 
  322.         but fortunately, they have the same value!
  323.  
  324.         Longer names - If you wish to be more explicit with procedure, 
  325.         function, and variable names, you can always add the unit name as 
  326.         a prefix:
  327.  
  328.            Qwik.GotoRC (1,1);
  329.            MyCols:=Qwik.CRTcols;
  330.  
  331.         Q* Convention - The "Q" in front of a procedure means that it 
  332. |       depends on the data initialized by Qinit.  Others do not.  In 
  333. |       addition, they keep track of the last character or attribute 
  334. |       written to the screen by updating QnextOfs (except Qstores* which 
  335. |       leaves it unaltered).
  336.  
  337.  
  338.         SPEED:
  339.  
  340.         How fast is fast?  Well, I thought it would be good idea to have
  341.         some criteria to get a feeling for speed.  The units I decided
  342.         to use for comparison are "screens/second".  To make one screen,
  343.         a procedure is repeated with a FOR loop to fill several 80x25
  344.         pages and timed.  Qwrite- use 80 character strings, and Qattr
  345.         and Qfill use Rows:=25 and Cols:=80.  Here are some samples from 
  346.         the systems that have been tested.  My own computer is the 
  347.         AT&T 6300+ which uses Intel 80286.  Monochrome (MDA) speeds are 
  348.         close to EGA speeds.
  349.  
  350.         ------------------ S C R E E N S / S E C O N D ------------------
  351.                    Chng  XT(4.77 MHz)  M30    M50    PCC      ATT 6300+
  352.         Procedure  Attr  EGA     CGA   MCGA   VGA    LCD     EGA     CGA     
  353.         ---------  ----  ------------  -----  -----  -----   -----------     
  354.         Qwrite      Yes   32.8   9.5    75.4   88.4   40.0   112.1  16.7
  355.                     No    42.4   9.5    90.0  138.1   48.6   119.5  16.8
  356.         QwriteC     Yes   32.6   9.5    74.9   89.0   39.5   111.0  16.8     
  357.                     No    41.6   9.5    89.3  138.1   47.8   119.0  16.8     
  358.         QwriteA     Yes   32.6   9.5    74.9   88.4   39.7   111.3  16.8     
  359.                     No    42.0   9.5    89.3  138.1   47.8   119.5  16.8     
  360.         QfillC      Yes   81.2  11.9   166.6  147.3  122.5   244.3  21.5     
  361.                     No    72.6   7.4   141.3  174.4   90.5   176.9  14.0     
  362.         Qfill       Yes   81.2  11.8   164.1  147.3  122.5   246.1  21.5     
  363.                     No    73.7   7.4   141.3  174.4   90.5   177.9  14.0     
  364.         Qattr       Yes   72.6   7.4   141.3  174.4   90.5   177.9  14.0     
  365.         QattrC      Yes   72.6   7.4   141.3  174.4   90.5   177.9  14.0     
  366.         QstoreToMem n/a   59.1   7.2   111.6  127.4   78.4   181.9  13.8     
  367.         QstoreToScr n/a   59.1   7.0   111.6  126.2   78.4   183.9  13.7     
  368.  
  369. |       For those interested in comparisons, QWIK is much faster than the 
  370. |       TP4 direct video routines and FastWrite by the following 
  371. |       percentage:
  372. |
  373. |            Procedure  CGA cards  All Other cards     
  374. |            ---------  ---------  ---------------     
  375. |            Writeln     125%       650%               
  376. |            FastWrite    25%        14%                     
  377.  
  378. |       CRITICAL TIMING:
  379. |
  380. |       The timing on the IBM PC (Intel 8088 at 4.77MHz) with a CGA is 
  381. |       critical for storing characters and attributes as words because of 
  382. |       the CPU architecture and slow speed.  Although previous versions 
  383. |       kept the timing as tight as possible, there still remained a hint 
  384. |       of snow in column 1.  This problem has now been solved with a 
  385. |       minor code change.  So the routines still run at the same speed, 
  386. |       but there is absolutely no snow!  I am not aware of any other 
  387. |       routines that have done this correctly.
  388.  
  389.  
  390.         CODE SIZE:
  391.  
  392.         If you use a QWIK procedure, the entire object file containing 
  393.         that procedure will be linked into your program no matter if its 
  394.         other procedures are used or not.  Fortunately, QWIK is quite 
  395.         small at a total of 1696 bytes.  Here's linked code size:
  396.  
  397.  
  398.         FILE NAME    BYTES  PROCEDURES
  399.         ------------ -----  ----------------------------------------------
  400.         Qinit   .obj  496   Qinit - always linked when QWIK is USEd
  401.         Qwrites .obj  341   Qwrite,QwriteC,QwriteA,QwriteMore,QwriteMoreA
  402.         Qfills  .obj  430   Qfill,Qattr,QfillC,QattrC,QfillMore,QattrMore
  403.         Qstores .obj  202   QstoreToScr,QstoreToMem
  404.         Qpages  .obj   56   QwritePage,QviewPage
  405.         Cursor  .obj  105   GotoRC,CursorChange,CursorOff/On,WhereR/C
  406.         CpuIdent.obj   42   GetCpuID
  407.         Qwik    .tpu   24   Initialize and paragraph round up 
  408.  
  409.  
  410.         APPLICATIONS:
  411.  
  412.         Multi-level Windows - An application of QWIK41A.TPU is multi-level 
  413.         windows.  The code is available in a file called WNDW40.ARC.  It 
  414.         creates protected windows with serial or random access that can be 
  415.         moved or removed and has Macintosh-like special special effects.
  416.  
  417.         Multi-level Pull-down Menus - An application of windows is multi-
  418.         level pull-down menus.  I have already created some very thorough 
  419.         code in a file called PULL20.ARC.  It is fully featured and fully 
  420.         configurable.  Includes execute, single, and multiple choice 
  421.         menus, unlimited nested submenus, data entry windows, help 
  422.         windows, directory windows, message system, and fully completed 
  423.         interfaces.
  424.  
  425.         On-line source - All updated files and later versions can be found 
  426.         on the CompuServe Borland Forum (GO BPROGA) in the MSDOS TP 4.0 
  427.         Data Library or the IBM software forum (GO IBMSW) data library.
  428.  
  429.  
  430.         CREDITS:
  431.  
  432.         Without the assistance and original ideas from Brian Foley
  433.         [CIS 76317,3247], these routines would not have been written. 
  434.  
  435.         Copyright (c) 1986-1988 by James H. LeMay
  436.  
  437.         If there are any problems, please let me know.
  438.         Jim LeMay [CIS 76011,217]  (1-817-735-4833  after 1800 CST)
  439.         6341 Klamath Rd., Ft. Worth, TX, 76116.
  440.  
  441.  
  442.         PRICE:
  443.  
  444.         After much thought, I have decided to make these procedures into 
  445.         ShareWare.  The cost may range from $8 to $18 depending on your 
  446.         application.  I do enjoy assisting others in their programming, 
  447.         but lack of reimbursement is expensive for me!  Please help out.  
  448.         See the license statement, STATMENT.LIC, in LICENSE.ARC for 
  449.         details.  If the response will let me break even, I will continue 
  450.         support.  
  451.  
  452.  
  453.         REVISIONS:
  454.  
  455.         Version 4.0 (12-01-87):
  456.           Converted QWIK30 to QWIK40 to work on Turbo Pascal 4.0.
  457.           Deleted QwriteV and QwriteCV.
  458.           Added WhereR and WhereC.
  459.           Added Hercules and IBM 3270 PC detection.
  460.           Renamed the following variables:
  461.             From       To
  462.             ---------- ------------
  463.             CardWait   CardSnow
  464.             Qwait      Qsnow
  465.             QwriteLV   QwriteA
  466.             QwriteCV   QwriteC
  467.             QwriteV    Qwrite
  468.             ActiveDD   ActiveDispDev
  469.             AltDD      AltDispDev
  470.             PCCAltDD   AltDispDevPCC
  471.             Vmode      VideoMode
  472.           Added the following variables:
  473.             VideoPage, CRTcols, CRTrows, CardSeg, Have3270, 
  474.             ActiveDispDev3270
  475.           Added the following constants:
  476.             NoHerc, HgcMono, HgcPlus, HercInColor
  477.           Types were changed on the following items:
  478.             - Strings passed to Qwrite* are of type String rather 
  479.               than Str80.  (Should not be of any consequence.)
  480.             - The CursorChange parameters are now word.
  481.             - EgaFontSize, CRTcolumns, CardSeg, Page0seg, Qseg, 
  482.                   AltDispDevPCC and ArrayLength are now word.
  483.  
  484.         Version 4.1a (05-01-88):
  485.           Added QwriteMore, QwriteMoreA, QfillMore, and QattrMore
  486.             procedures.
  487.           Added QnextOfs for the Q*More procedures.
  488.           Improved video detection in Qinit for dual monitors, Hercules 
  489.             cards, and system hardware detection.
  490.           Included background color constants to use instead of an 
  491.             attribute function.
  492.           Reduced code size about 10%.
  493.           Solved critical timing problem on IBM PC with CGA - at last!
  494.           QWIK now uses the global variable CRTcols and not the absolute 
  495.             variable CRTcolumns for offset calculations.